Skip to content

Conversation

@gregsdennis
Copy link
Member

What kind of change does this PR introduce?

Clarification

Issue & Discussion References

Summary

Adds a requirement to $schema that its value cannot contain a fragment. This prevents someone from using a non-canonical IRI in this keyword.

Does this PR introduce a breaking change?

Technically, yes, but the likelyhood of people using fragments in $schema is low (probably non-zero, though).

@gregsdennis gregsdennis added this to the stable-release milestone Sep 21, 2025
@gregsdennis gregsdennis requested a review from a team September 21, 2025 05:26
@gregsdennis gregsdennis self-assigned this Sep 21, 2025
@gregsdennis gregsdennis moved this to In Progress in Stable Release Development Sep 21, 2025
Copy link
Member

@jdesrosiers jdesrosiers left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm surprised to see a PR for this. I didn't think there was a consensus on this issue. The discussion just petered out without a clear resolution. I'm providing a review for this result, but I think we need to make sure this is the resolution we want before merging.


My first thought was that we can't do this because older dialect URIs use fragments, but then I realized I don't really know how this would affect older releases. It's a weird chicken and egg problem. I feel like $schema needs to be consistent across releases because it's what's used to determine which release to use. You don't know what version of $schema to use until you read its value.

I think that leaves us with two options: (1) allow (but discourage) an empty fragment, or (2) acknowledge the historic exceptions to the rule.

@karenetheridge
Copy link
Member

I like option 2 -- it exactly covers what we want to do while accomodating the existence of older drafts.

We should still be able to disallow fragments (even empty ones), while still allowing the use of the draft7 and earlier schemas in a new implementation, even with a restriction in the metaschema itself (e.g. with the pattern keyword) -- as a schema should not be getting validated against a metaschema other than the one specified in the $schema keyword.

We would just need to point out the exception for older schemas, so the implementation doesn't reject the use of an empty fragment before considering if an older draft's semantics should apply.

Co-authored-by: Jason Desrosiers <jdesrosi@gmail.com>
@gregsdennis
Copy link
Member Author

gregsdennis commented Dec 21, 2025

By allowing these, are we saying that all historical schemas are valid v1 schemas that just use different dialects, e.g. a draft 6 dialect? Otherwise it seems to me that those schemas would be valid under their own spec versions but not v1, and thus we don't need to state the exception.

This is the change I worked up:

The value of this keyword MUST be an
[absolute IRI](https://www.rfc-editor.org/info/rfc3987) (without a fragment). This
IRI MUST be normalized. Exceptions exist for previous versions of this
specification and meta-schemas based on those version, which have fragments
defined in their `$schema` values, namely:

- `http://json-schema.org/draft-03/schema#`
- `http://json-schema.org/draft-04/schema#`
- `http://json-schema.org/draft-06/schema#`
- `http://json-schema.org/draft-07/schema#`

But it seems odd to explicitly reference older versions like this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

🧹 Clarification: usage of non-canonical identifiers in $schema

4 participants